package cn.song.freight.service;

import cn.song.freight.domain.dto.StrategyAreaPricingDTO;
import cn.song.freight.domain.entity.StrategyAreaPricingDO;
import cn.song.freight.domain.result.R;
import com.baomidou.mybatisplus.extension.service.IService;

import java.util.List;

/**
 * 策略区域定价服务接口（V3版本核心业务组件）
 * <pre>
 * 该服务是V3版本架构的核心业务组件，负责管理运费策略的定价配置信息。
 * 适配新的数据关系架构：定价配置与区域分离管理，通过映射表关联。
 * 实现V3版本定义的4个核心方法，提供完整的CRUD操作和业务查询能力。
 *
 * V3版本架构优势：
 * 1. 关注点分离：定价配置与区域管理分离，降低系统复杂度
 * 2. 灵活性提升：一个定价配置可复用于多个区域，提高配置效率
 * 3. 扩展性增强：支持未来更复杂的价格策略和业务规则
 * 4. 数据一致性：通过事务管理和级联删除保证数据完整性
 * 5. 性能优化：减少数据凗余，提高查询和更新效率
 *
 * 核心业务能力：
 * - 定价配置管理：创建、更新、删除定价配置，支持完整的生命周期管理
 * - 智能匹配查询：根据策略和区域信息自动匹配适用的定价配置
 * - 批量查询支持：按策略维度批量查询定价配置，支持业务批量处理
 * - 数据一致性维护：在删除定价配置时自动清理相关的区域映射
 *
 * 定价配置结构说明：
 * - 基础信息：配置名称、策略关联、创建更新时间等
 * - 首重配置：首重重量限制和对应的费用设置
 * - 续重配置：续重计费单位和对应的单位费用
 * - 体积重配置：抛重比率设置，用于体积重量计算
 * - 特殊设置：支持业务特殊需求的扩展字段
 *
 * 事务安全保证：
 * - 事务边界明确：所有写操作都具备事务回滚能力
 * - 异常处理完善：对各种异常情况提供明确的错误信息
 * - 数据校验严格：对输入数据进行全面校验和清洗
 * - 级联操作安全：在删除操作中保证相关数据的一致性
 *
 * 性能优化特性：
 * - 懒加载策略：避免不必要的数据加载和处理
 * - 批量查询优化：减少数据库往返次数，提高查询效率
 * - 查询结果缓存：为高频查询提供缓存支持（预留接口）
 * - 业务逻辑优化：在应用层完成复杂逻辑，减少数据库压力
 *
 * @author SongRenShuo
 * @version 3.0.0
 * @since 2025-08-25
 */
public interface StrategyAreaPricingService  extends IService<StrategyAreaPricingDO> {
    /**
     * 新增定价配置（V3版本核心创建方法，支持完整的数据校验）
     * <pre>
     * 该方法是V3版本架构中定价配置的核心创建入口，负责创建新的运费定价配置。
     * 通过严格的数据校验、业务规则检查和事务管理，确保数据的完整性和一致性。
     *
     * 主要特性：
     * - 全面数据校验：对输入数据进行多层次校验，确保数据质量
     * - 业务规则检查：验证关联策略的存在性和有效性
     * - 事务安全保证：支持事务回滚，确保操作的原子性
     * - 明确的错误反馈：提供详细的错误信息和处理建议
     * - 自动ID生成：数据库自动生成主键ID，并返回给调用方
     *
     * 数据校验项：
     * - 必需字段检查：配置名称、策略ID、各种重量和费用参数
     * - 数值范围校验：重量和费用参数的合理性检查
     * - 业务逻辑校验：首重与续重参数的逻辑一致性
     * - 关联数据检查：验证关联策略的存在性和状态
     *
     * @param dto 定价配置DTO对象，包含以下必要信息：
     *            - name: 配置名称（必需，非空）
     *            - strategyId: 关联策略ID（必需，大于0）
     *            - firstWeightKg: 首重重量（必需，大于0）
     *            - firstWeightFee: 首重费用（必需，大于等于0）
     *            - additionalWeightKg: 续重单位（必需，大于0）
     *            - additionalWeightFee: 续重费用（必需，大于等于0）
     *            - volumetricWeightRatio: 抛重比率（必需，大于0）
     * @return R<Long> 封装的响应结果：
     *         - 成功：返回新创建的定价配置ID
     *         - 失败：返回包含详细错误信息的结果
     * @throws RuntimeException 当数据库操作异常时抛出，事务会自动回滚
     * @since 3.0.0
     */
    R<Long> addPricingConfig(StrategyAreaPricingDTO dto);

    /**
     * 更新定价配置（V3版本核心更新方法，支持完整的数据校验和版本控制）
     * <pre>
     * 该方法是V3版本架构中定价配置的核心更新入口，负责修改已存在的运费定价配置。
     * 通过严格的存在性验证、数据校验和事务管理，确保更新操作的安全性和一致性。
     * 支持部分字段更新和完整性约束检查，防止无效的配置更新。
     *
     * 主要特性：
     * - 存在性验证：确保待更新的配置确实存在于数据库中
     * - 数据完整性校验：对更新数据进行全面的业务规则检查
     * - 版本控制支持：自动更新updateTime字段，支持乐观锁机制
     * - 事务安全保证：支持事务回滚，确保操作的原子性
     * - 增量更新优化：仅更新变更的字段，提高更新效率
     * - 详细错误反馈：提供明确的错误信息和处理建议
     *
     * 更新策略：
     * - 保持主键ID不变：确保关联关系的稳定性
     * - 保留createTime：维护数据的历史追踪能力
     * - 更新updateTime：自动记录最后修改时间
     * - 全字段覆盖：使用新数据完全替换现有配置（除系统字段外）
     *
     * 业务规则检查：
     * - 必需字段完整性：确保所有必需字段都有有效值
     * - 数值合理性：验证重量和费用参数的业务合理性
     * - 逻辑一致性：检查首重续重参数的逻辑关系
     * - 关联完整性：验证关联策略的存在性和有效性
     *
     * @param dto 定价配置DTO对象，包含以下关键信息：
     *            - id: 待更新的配置ID（必需，用于定位记录）
     *            - name: 更新后的配置名称（必需，非空）
     *            - strategyId: 关联策略ID（必需，不建议修改）
     *            - firstWeightKg: 更新后的首重重量（必需，大于0）
     *            - firstWeightFee: 更新后的首重费用（必需，大于等于0）
     *            - additionalWeightKg: 更新后的续重单位（必需，大于0）
     *            - additionalWeightFee: 更新后的续重费用（必需，大于等于0）
     *            - volumetricWeightRatio: 更新后的抛重比率（必需，大于0）
     * @return R<Boolean> 封装的响应结果：
     *         - 成功：返回true，表示更新操作成功完成
     *         - 失败：返回false，并包含详细的错误信息
     * @throws RuntimeException 当数据库操作异常时抛出，事务会自动回滚
     * @since 3.0.0
     */
    R<Boolean> updatePricingConfig(StrategyAreaPricingDTO dto);

    /**
     * 删除定价配置（V3版本核心删除方法，支持级联删除和安全验证）
     * <pre>
     * 该方法是V3版本架构中定价配置的核心删除入口，负责安全地删除运费定价配置。
     * 通过存在性验证、级联数据清理和事务管理，确保删除操作的安全性和数据一致性。
     * 在删除定价配置之前，会自动清理所有相关的区域映射关系，避免孤儿数据的产生。
     *
     * 核心安全特性：
     * - 存在性验证：确保待删除的配置确实存在于数据库中
     * - 级联数据清理：自动删除所有相关的区域映射关系
     * - 事务安全保证：支持事务回滚，确保操作的原子性
     * - 数据一致性：防止孤儿数据和无效引用的产生
     * - 详细日志记录：记录删除操作的详细过程和结果
     * - 明确错误反馈：提供清晰的错误信息和处理建议
     *
     * 删除策略执行顺序：
     * 1. 参数有效性验证 → 确保输入参数的合法性
     * 2. 存在性检查 → 验证目标记录是否存在
     * 3. 级联数据清理 → 删除所有相关的区域映射
     * 4. 主记录删除 → 删除定价配置本身
     * 5. 结果验证和日志记录 → 确保操作成功并记录
     *
     * 注意事项：
     * - 该操作不可逆：一旦删除成功，相关数据无法恢复
     * - 影响范围：会同时删除所有相关的区域映射关系
     * - 业务影响：删除后相关区域的运费计算可能失效
     * - 数据一致性：确保全部相关数据的一致删除
     *
     * @param id 待删除的定价配置ID（必需，大于0的有效ID）
     * @return R<Boolean> 封装的响应结果：
     *         - 成功：返回true，表示删除操作成功完成
     *         - 失败：返回false，并包含详细的错误信息和处理建议
     * @throws RuntimeException 当数据库操作异常时抛出，事务会自动回滚
     * @since 3.0.0
     */
    R<Boolean> deletePricingConfig(Long id);

    /**
     * 查找适用的定价配置（V3版本优化算法，避免for循环中的数据库查询）
     * <pre>
     * 该方法是V3版本架构的核心查询方法，负责根据策略ID和区域ID查找适用的定价配置。
     * 通过优化的数据库查询策略，将原本在for循环中的逐个查询优化为批量查询。
     *
     * 查询策略：
     * 1. 通过区域ID查找所有相关的映射关系
     * 2. 批量获取所有相关的定价配置信息
     * 3. 在内存中进行策略匹配，避免多次数据库交互
     *
     * 性能优化亮点：
     * - 批量查询：从1+N次查询优化为2次查询（N为映射数量）
     * - 内存计算：在应用层完成数据匹配，减少数据库负载
     * - 早期退出：找到匹配结果后立即返回，避免不必要的计算
     * - 类型安全：使用对象集合操作，避免空指针异常
     *
     * @param strategyId 运费策略ID（必需，用于精确匹配）
     * @param areaId 目标区域ID（必需，用于查承映射关系）
     * @return R<StrategyAreaPricingDO> 封装的响应结果：
     *         - 成功：返回匹配的定价配置对象
     *         - 失败：返回包含错误信息的结果
     * @throws RuntimeException 当数据库操作异常时抛出
     * @since 3.0.0
     */
    R<StrategyAreaPricingDO> findApplicablePricingConfig(Long strategyId, Long areaId);

    /**
     * 按策略ID查询所有相关的定价配置（支持批量查询和排序）
     * <pre>
     * 该方法为上层业务提供批量查询能力，支持一次性获取某个策略下的所有定价配置。
     * 结果按创建时间降序排列，确保最新配置优先显示，提供更好的用户体验。
     *
     * 使用场景：
     * - 策略配置管理界面：显示某个策略下的所有定价配置
     * - 批量操作处理：为批量更新或删除提供数据基础
     * - 业务报表统计：统计某个策略的配置数量和详情
     * - 数据导出功能：支持策略配置的导出和备份
     *
     * 性能特性：
     * - 高效查询：使用数据库索引优化，查询性能优异
     * - 内存友好：返回的是实际数据列表，不进行额外的包装
     * - 空结果安全：对空参数和无结果情况进行安全处理
     * - 日志记录完善：提供详细的查询统计和结果信息
     *
     * @param strategyId 运费策略ID（必需，用于精确匹配）
     * @return List<StrategyAreaPricingDO> 定价配置列表：
     *         - 非空：返回按创建时间降序排列的配置列表
     *         - 空结果：返回空列表（不返回null）
     * @since 3.0.0
     */
    List<StrategyAreaPricingDO> getByStrategyId(Long strategyId);
}
